现在用于RESTFul API设计的工具主要是三种,分别是Swagger,API Bluprint, RAML。 与其说他们是工具，不如说他们是RESTFul API的定义规范描述语言，只是在围绕着这些规范语言各自有各自的生态系统，下面我会简单介绍一下着三中规范描述语言，以及他们的优劣。个人观点会强烈地倾向RAML，虽然只是简单的看了看，但是觉得RAML的语法更清晰，所以文章中有很多地方会让人觉得个人倾向RAML很严重，请见谅。
Swagger
当前版本：2.0
官方网站
主要使用JSON方式来描述API的定义(现在也支持YAML语法)，例子请参考swagger
Swagger的语法已经接近RAML了，但是内部还是主要用json格式来做描述。由于在国内业务企业级开发的阵营中，java的地位暂时无法撼动，所以我们使用Sagger的方式也和java有很大关系，如何使用呢，我所在的公司还有我的一些朋友都是以spring boot作为基础的脚手架，然后在controller里面直接加上注解，标明每个参数的作用等，然后在熊他老公启动后，swagger自动扫描这些注解并且动态生成对应的接口定义，在你访问http://your.domain.com/{context}/api-docs 的时候就会把你所有定义的接口可视化渲染出来，基本上我们不会去自己定义API规范，然后导出代码。一方面是比较麻烦，二来导出的代码我们也不一定好用，主要是与自己使用的脚手架不一定兼容。
API Blueprint
当前版本：无
官方网站
主要使用markdown来描述API的使用，语法个人觉得比较晦涩，使用#和+来标示request和response，然后在通过工具将markdown的内容转化为json格式，供机器使用。个人觉得这种方式好变态，所以没有深入研究。
RAML
当前版本 0.8
官方网址
主要使用yaml语言方式在描述API的定义,本来我觉得RAML和swagger2.0的定义基本上没有太大的不同，但是我发现RAML支持include别的yml文件，这个比swagger要先进很多，基本上sagger文件里面也会有全局定义，使用$ref来引用，但是总有一些scheme需要全局定义的，特别是在大型的企业化工程里面，例如我用需要统一的error定义，统一的auth定义，统一code定义，这些在swagger里面需要在每个单独的domian里面定义，很繁琐。
虽然在我的工作中，主要还是用到swagger来做API设计，但是仅限于在java中使用注解的方式来对接口进行描述，而且接口可视化都是在本地直接显示的，并没有接入server集中显示。所以纯粹写描述文件的方式对我来说都是一样的，不过个人倾向是RAML，在接下来的工作中，慢慢去使用，到时候再写篇实践心得分享给大家。
